BCI NET

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET / BCI NET Dec 94.iso / archives / programming / libraries / sslib41.lha / SSLib.doc < prev next >

Wrap

Text File | 1994-06-03 | 56.0 KB | 2,098 lines

TABLE OF CONTENTS ss.library/AddExtension ss.library/AddHashItem ss.library/CallBlock ss.library/ChkDoIO ss.library/ChkRead ss.library/ChkWrite ss.library/CreateResList ss.library/DisplayError ss.library/DosError ss.library/ExitCleanup ss.library/ExitError ss.library/FindHashItem ss.library/FormatString ss.library/FreeAllResLists ss.library/FreeObject ss.library/FreeResList ss.library/GetExtension ss.library/GetResList ss.library/InitHashTree ss.library/LinearAlloc ss.library/LinearAllocN ss.library/LoadFile ss.library/MergeResLists ss.library/ParseArgs ss.library/PoolAlloc ss.library/PoolFree ss.library/Printf ss.library/Puts ss.library/PutsNL ss.library/QuickSort ss.library/RelinkObject ss.library/RemExtension ss.library/ReportError ss.library/SetExtension ss.library/SimpleRequest ss.library/SortList ss.library/SortListName ss.library/SortLongs ss.library/SortStrings ss.library/StartupInit ss.library/StrCat ss.library/StrToL ss.library/TestBreak ss.library/TestStack ss.library/TrackAlloc ss.library/TrackAlloc ss.library/TrackAllocPub ss.library/TrackDevice ss.library/TrackDosObject ss.library/TrackExtd ss.library/TrackIoRq ss.library/TrackLibrary ss.library/TrackLinPool ss.library/TrackLock ss.library/TrackObject ss.library/TrackOpen ss.library/TrackPool ss.library/TrackPort ss.library/TrackRoutine ss.library/TrackSignal ss.library/TrackSlave ss.library/AddExtension ss.library/AddExtension NAME AddExtension -- Add extension to file name. SYNOPSIS Success = AddExtension(Name, Buffer, Extension, BufSize); D0 A0 A1 A2 D0 FUNCTION Appends an extension to file name. If there's already some extension at the end of the name, nothing happens. INPUTS Name - original file name Buffer - buffer to copy the result to Extension - extension to be added BufSize - size of the buffer RESULT Success - TRUE if successful, FALSE if buffer overflow. SEE ALSO SetExtension, GetExtension, RemExtension ss.library/AddHashItem ss.library/AddHashItem NAME AddHashItem -- Add item to hashed tree. SYNOPSIS UserData = AddHashItem(Tree, ItemName, DataSize); D0 A0 A1 D0 FUNCTION Add an item to hashed tree performing no checking of duplicity (if you make duplicated entries, some of them will be lost and cannot be found by any method, but are correctly freed if you free the tree). The item contains your own data area of specified size. INPUTS Tree - hashed tree represented by its tracker ItemName - text key representing the item DataSize - the size of your data area for the item (0-32766, must be even!) RESULT UserData - Pointer to user data area of the item. This data area is preceeded by one word containing size of the area. The area is succeeded by key string. SEE ALSO InitHashTree, FindHashItem, FreeObject ss.library/CallBlock ss.library/CallBlock NAME CallBlock -- Call a subprogram. SYNOPSIS Failure = CallBlock(Routine, LeaveResources); D0 A0 D0 FUNCTION Calls a subprogram. If the subprogram fails or LeaveResources=0, all resources allocated by it are freed. If it doesn't fail and LeaveResources<>0, these resources are added to current resource list of the caller. Registers D1-D7/A0-A6 are passed to called subprogram without changes. If it returns normally, D1-D7/A0-A4/A6 are passed back to the caller. In case of failure (return via ExitError), D2-D7/A2-A6 contain their original values (before call), values of D1/A0-A1 are unexpectable. INPUTS Routine - address of subroutine to be called LeaveResources - boolean value indicating that you want the resources allocated by the subprogram to be allocated. If not set, they are freed automatically before return. RESULT Failure - non-zero value if the routine has failed. NOTE The called subprogram is not allowed to create its own resource lists. SEE ALSO MergeResLists ss.library/ChkDoIO ss.library/ChkDoIO NAME ChkDoIO -- Perform an I/O operation and test error. SYNOPSIS Error = ChkDoIO(Message, DeviceTracker); D0 A0 A1 FUNCTION This function acts like DoIO in exec.library with the following differences, which make it easier to use in programs doing simple I/O: - IO_FLAGS are NOT set to $01 (DoIO does it, but ChkDoIO sets only the IOB_QUICK bit). It makes ChkDoIO capable of handling I/O commands requiring special information in flags. - While waiting for finish of the operation, the user may hit CTRL-C and try to abort it. - If err_iofail and err_iofail2 bits are set, ChkDoIO does automatic processing of I/O errors. In this case, it uses the error table stored in the device tracker (see TrackDevice) and the custom error string. If the error string has been found, "<Message> - <error string>" is displayed and err_iofail2 is used. In other cases, "<Message> - <xxx.device> error <errcode>" and err_iofail is used. INPUTS Message - optional error message (if NULL, "I/O error" will be used) DeviceTracker - tracker of device to perform the I/O operation with. It must contain reference to the error table (may be NULL). RESULT Error - error code or 0 if successful. WARNING It is not possible to use ChkDoIO on device trackers which don't contain the error table. A NULL pointer is a valid error table. SEE ALSO TrackDevice, exec/DoIO ss.library/ChkRead ss.library/ChkRead NAME ChkRead -- Read from file and test error. SYNOPSIS Success = ChkRead(Tracker, Buffer, Size); D0 A0 A1 D0 FUNCTION Read from file and report any errors. The file tracker is used instead of file handle, because it contains file name used for error reporting. The report is generated whenever the size of read data is not equal to the size specified as a parameter, therefore ChkRead cannot be used for reading from interactive files (consoles etc.). INPUTS Tracker - tracker of file to read the data from. Buffer - buffer to read the data to. Size - size of block you want to read. RESULT Success - boolean value indicating success. WARNING File name specified by a call to TrackFile must be still on its place and mustn't be changed in any way. SEE ALSO ChkWrite, TrackOpen, LoadFile ss.library/ChkWrite ss.library/ChkWrite NAME ChkWrite -- Write to file and test error. SYNOPSIS Success = ChkWrite(Tracker, Buffer, Size); D0 A0 A1 D0 FUNCTION Write to file and report any errors. The file tracker is used instead of file handle, because it contains file name used for error reporting. The report is generated whenever the size of written data is not equal to the size specified as a parameter. INPUTS Tracker - tracker of file to write the data to. Buffer - address of data to be written. Size - size of block you want to write. RESULT Success - boolean value indicating success. WARNING File name specified by a call to TrackFile must be still on its place and mustn't be changed in any way. SEE ALSO ChkRead, TrackOpen ss.library/CreateResList ss.library/CreateResList NAME CreateResList -- Create new resource list. SYNOPSIS ResList = CreateResList(); D0 FUNCTION Create local resource list. It can be useful if you need to have local resources allocated in some part of program and freed after leaving it and you don't want to free them separately by FreeObject(). RESULT ResList - Pointer to created ResourceList structure. SEE ALSO FreeResList, FreeAllResLists ss.library/DisplayError ss.library/DisplayError NAME DisplayError -- Display error message without exiting. SYNOPSIS DisplayError(Text, Params); A0 A1 FUNCTION Display an error message using standard or user-supplied error displaying mechanism (it defaults to writing of the message into standard output if it exists or to displaying a requester with it if started from WB with no console window). Using of requesters (equivalent to SimpleRequest(A0,A1,"Exit")) for the default error routine can be forced by the ssf_errorreq flag or the sst_errorreq tag. This function automatically adds an exclamation mark ('!') to the message and is able to process printf-style arguments. It's better if the error message isn't longer than one line. INPUTS Text - pointer to message you want to display (MUSTN'T EXCEED 200 BYTES!!!) Params - pointer to optional parameters used for printf-style formatting SEE ALSO ExitError, DosError, ReportError, SimpleRequest, exec/RawDoFmt ss.library/DosError ss.library/DosError NAME DosError -- Exit with DOS error. SYNOPSIS DosError(Text, Params); A0 A1 FUNCTION Display an error message followed by DOS fault string explaining why did error happen. The DOS error number is determined from the dos/IoErr() function, therefore you must call DosError() directly after the function, which caused the error without calling any other DOS functions (directly or indirectly). The program is terminated via standard exit mechanism with return code according to sv_errrc. If IoErr() returns zero (no error cause known), the supplied message is simply passed to ExitError(). If there is no such message, "Unknown DOS Error" is used. INPUTS Text - message text, can be empty (in this case, only the fault string is shown). Params - pointer to optional parameters used for printf-style formatting. NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO ExitCleanup, ExitError ss.library/ExitCleanup ss.library/ExitCleanup NAME ExitCleanup -- Clean up and exit. SYNOPSIS ExitCleanup(); FUNCTION This service exits the program after performing some cleanup actions: - A5 is tested for correct value. If it contains garbage, the current task is searched for in the caller table. If it isn't found, the alert AN_ExitCrash is displayed. (this very fatal situation shouldn't occur). - the user's exit routine (sv_exitrout) is called. - all tracked resources are freed using FreeAllResLists(). - all arguments supplied by DOS are freed. - the block of variables pointed to by A5 is freed. - some other actions which needn't to be described here. RESULT Completely clean environment (all objects can be recycled...) NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO StartupInit, ExitError, DosError ss.library/ExitError ss.library/ExitError NAME ExitError -- Display error message and exit. SYNOPSIS ExitError(Text, Params); A0 A1 FUNCTION Display an error message using DisplayError and exit the program with return code sv_errrc. It's better if the error message isn't longer than one line. INPUTS Text - pointer to error message (MUSTN'T EXCEED 200 BYTES!!!) Params - optional pointer for parameters used for printf-style formatting RESULT Horrified user. NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO DisplayError, ExitCleanup ss.library/FindHashItem ss.library/FindHashItem NAME FindHashItem -- Find item in hashed tree. SYNOPSIS UserDate = FindHashItem(Tree, ItemName); D0 A0 A0 FUNCTION Find an item in hashed tree. It's able to find only one occurence of given string. INPUTS Tree - hashed tree represented by its tracker ItemName - text key to find RESULT UserDate - Pointer to user data area of the item. (Additional fields reachable from this point are listed in AddHashItem doc). NULL if not found. SEE ALSO InitHashTree, AddHashItem, FreeObject ss.library/FormatString ss.library/FormatString NAME FormatString -- Format data according to template. SYNOPSIS FormatString(Format, Data, DestBuf); A0 A1 A2 FUNCTION This function performs something like sprintf() in C. It calls exec/RawDoFmt with simple PutC routine, which stores all characters into supplied destination buffer. INPUTS Format - pointer to format string Data - pointer to parameters DestBuf - pointer to destination buffer ss.library/FreeAllResLists ss.library/FreeAllResLists NAME FreeAllResLists -- Free all resource lists. SYNOPSIS FreeAllResLists(); FUNCTION Free all tracked resources in all resource lists and discard all the lists. Used by ExitCleanup(). SEE ALSO FreeResList, ExitCleanup ss.library/FreeObject ss.library/FreeObject NAME FreeObject -- Free tracked object. SYNOPSIS FreeObject(Tracker); A0 FUNCTION Free tracked object and remove the tracker. For master trackers, free all slave trackers. All trackers, which are not freed by calling of this service, will be freed during the ExitCleanup process. It will be done in reverse order of their tracking. Trackers connected as slaves will be handled as usually (see below). The freeing routines may fail. In this case, the resource freeing process will be started again and the tracker will be freed without calling the routine which caused the failure. The freeing routine for given tracker type is called only if the trk_data field is not 0. But the tracker itself is freed in any case. If you free a tracker, which is a slave of some other tracker, the tracked resource is correctly freed, but the tracker node remains in memory until the master tracker is freed. INPUTS Tracker - pointer to tracked object to be freed. SEE ALSO FreeResList, Track#?, FreeAllResLists, ExitCleanup ss.library/FreeResList ss.library/FreeResList NAME FreeResList -- Free resource list. SYNOPSIS FreeResList(); FUNCTION Free all tracked objects in the top-level resource list and remove the list. Used to free local resource lists. The object are removed in head-to-tail order, therefore the object list acts as a LIFO buffer. SEE ALSO CreateResList, FreeAllResLists, FreeObject, Track#?, ExitCleanup ss.library/GetExtension ss.library/GetExtension NAME GetExtension -- Get filename extension. SYNOPSIS Extension = GetExtension(Name); D0 A0 FUNCTION Get last extension of given filename. INPUTS Name - file name you want to get extension of RESULT Extension - Pointer to extension of the file name. If there's no extension, the pointer points to the trailing NULL character of the name. NOTE A0=D0 on exit. SEE ALSO AddExtension, GetExtension, RemExtension ss.library/GetResList ss.library/GetResList NAME GetResList -- Get pointer to current resource list. SYNOPSIS RList = GetResList(); D0 FUNCTION Get current top-level resource list. If there is no resource list, new one is created. RESULT RList - pointer to the resl_list item of the top-level resource list. NOTE A0=D0 on exit. SEE ALSO CreateResList, FreeResList, Track#? ss.library/InitHashTree ss.library/InitHashTree NAME InitHashTree -- Initialize a hashed tree. SYNOPSIS Tracker = InitHashTree(TableSize, Flags); D0 D0 D1 FUNCTION Initialize a hashed tree. The hashed tree is a simple structure containing data items accessed using text key. SS Library allows to simply manage these trees with both case-dependent and case-independent key searching. INPUTS TableSize - number of entries in the hash table. Each entry occupies 4 bytes. Must be a power of 2 between 8 and 32768. Flags - htf_nocase if all the comparisons have to be performed in case-insensitive manner. It is significantly slower than the default case-sensitive algorithm. RESULT Tracker - hashed tree tracker. The tree is referenced always by this tracker. SEE ALSO AddHashItem, FindHashItem, FreeObject ss.library/LinearAlloc ss.library/LinearAlloc NAME LinearAlloc -- Allocate word-aligned space in linear pool. SYNOPSIS Mem = LinearAlloc(Pool, Size); D0 A0 D1 FUNCTION Allocates memory in given linear memory pool (created by TrackLinPool). If Size is less or equal to free space in current memory chunk, the memory is taken from it. In all other cases, new memory chunk is created. If Size>Quantum, the new chunk is expanded to satisfy the request. INPUTS Pool - tracker of linear memory pool to allocate the block in Size - requested size RESULT Mem - Pointer to allocated memory block (always even) or NULL if no memory available and err_memory disabled. NOTE If you don't depend on evenness of the allocated block, use LinearAllocN instead. FUNCTION Allocation of 0 bytes is allowed. INPUTS Pool - tracker of linear memory pool to allocate the block in Size - requested size RESULT Mem - Pointer to allocated memory block (always even) or NULL if no memory available and err_memory disabled. WARNING The Size parameter is given in D1 and NOT in D0 as usually the first non-address parameter is. SEE ALSO TrackLinPool, LinearAllocN ss.library/LinearAllocN ss.library/LinearAllocN NAME LinearAllocN -- Allocate unaligned space in linear pool. SYNOPSIS Mem = LinearAllocN(Pool, Size); D0 A0 D1 FUNCTION Allocates memory in given linear memory pool (created by TrackLinPool). Doesn't word-align the allocation, therefore is usually used for allocation of strings. Slightly faster than LinearAlloc. If Size is less or equal to free space in current memory chunk, the memory is taken from it. In all other cases, new memory chunk is created. If Size>Quantum, the new chunk is expanded to satisfy the request. Allocation of 0 bytes is allowed. INPUTS Pool - tracker of linear memory pool to allocate the block in Size - requested size RESULT Mem - Pointer to allocated memory block (may be odd) or NULL if no memory available and err_memory disabled. WARNING The Size parameter is given in D1 and NOT in D0 as usually the first non-address parameter is. SEE ALSO TrackLinPool, LinearAlloc ss.library/LoadFile ss.library/LoadFile NAME LoadFile -- Load whole file to memory. SYNOPSIS File, Tracker = LoadFile(FileName); D0 D1 A0 FUNCTION Read file from disk to memory. Uses TrackOpen, TrackMem and ChkRead and reports their errors if enabled. This function is able to decrunch powerpacked files using powerpacker library. Encrypted files are not supported yet. Error processing mechanism depends on err_openread and err_read error bits. INPUTS FileName - pointer to name of file you want to read. RESULT File - Pointer to file in memory. The file is preceeded by one longword containing file size in bytes and is always null-terminated (useful mostly for text files). Zero when unsuccessful and the default error processing is disabled. Tracker (D1) - Tracker of memory area containing the file or NULL if unsuccessful. BUGS Reading from interactive filehandles is not implemented, because it is not possible to estimate size of interactive file. If requested, appropriate error message is displayed. SEE ALSO ChkRead, TrackOpen, TrackAlloc, FreeObject ss.library/MergeResLists ss.library/MergeResLists NAME MergeResLists -- Merge two resource lists to one. SYNOPSIS MergeResLists(); FUNCTION Merges current resource list with the previous one. Returns without doing any action if less than two resource lists are defined. Used when you want to track some objects and connect them to the main resource list, but if some allocation fails, all the allocated objects have to be freed without freeing of the main resource list: CreateResList(); -- do the allocations here -- if (Failed) FreeResList(); else MergeResLists(); In many cases, it's better to use CallBlock which does many things automatically. SEE ALSO CreateResList, FreeResList, CallBlock ss.library/ParseArgs ss.library/ParseArgs NAME ParseArgs -- Parse CLI Argument String. SYNOPSIS Success, Tracker = ParseArgs(Source, Template, ExtraHelp, D0 D1 A0 A1 A2 Destination, Flags); A3 D0 FUNCTION Parse arguments. This function does something similar to dos/ReadArgs, but there are some little enhancements: - Automatic processing of errors (the program is automatically halted after error if it isn't disabled by the corresponding flag bit). - Ability to process non-decimal numbers in /N arguments (see StrToL). - Tracking functions are used for allocation of additional memory. - Provides mechanism for processing of default settings of non-/A arguments. - Arguments specified in default settings may be overriden or disabled by placing the minus ("-") sign before their keywords. For example: Let's have the template "NAME/K,SWITCH/S,ANOTHER/S" Default is "NAME Something ANOTHER" Parameters are "NAME Suspicious -ANOTHER SWITCH" Result is: NAME="Suspicious", ANOTHER=FALSE, SWITCH=TRUE The typical example of using ParseArgs with defaults is: if (! ParseArgs(Defaults,Template,&Vars,pafm_nofail | pafm_ignorea)) Report_Bad_Defaults; ParseArgs(Arguments,Template,&Vars,pafm_noclear); !! The /A arguments aren't taken from the defaults. INPUTS Source - string to be parsed. NULL means that the string has too be fetched from the standard buffered input (this is where the default arguments are stored by the shell). Template - template describing the arguments. ExtraHelp - an extra help string to be displayed when the user enters '?' the second time. Destination - the array you want to store the arguments to. Flags - some flags controlling the parsing (see below). RESULT Success - boolean value indicating success (always true when the automatic error processing is turned on). Tracker (D1) - object tracker of buffers associated with the result of the parsing. FLAGS pafb_nofail - disable automatic processing of errors pafb_noclear - don't clear the array before parsing pafb_ignorea - don't check presence of /A arguments NOTE You can freely modify the arguments returned by this function. SEE ALSO StartupInit, StrToL, dos/ReadArgs ss.library/PoolAlloc ss.library/PoolAlloc NAME PoolAlloc -- Allocate memory in private pool. SYNOPSIS Block = PoolAlloc(Pool, Size); D0 A0 D0 FUNCTION Allocates memory in given memory pool (created by TrackPool). If Size is less or equal to Threshold of memory pool, the block is allocated inside some chunk. If there is no free chunk, new one is created. Large memory blocks are allocated separately and linked to the pool. Attempt to allocate 0 bytes of memory results in alert AN_AllocZero and termination of your program. INPUTS Pool - tracker of memory pool you want to allocate the block in Size - requested size RESULT Block - Pointer to allocated memory block. SEE ALSO TrackPool, PoolFree ss.library/PoolFree ss.library/PoolFree NAME PoolFree -- Free memory in private pool. SYNOPSIS PoolFree(Pool, Chunk, Size); A0 A1 D0 FUNCTION Frees memory allocated by PoolAlloc. Partial freeing is not allowed. INPUTS Pool - address of memory pool the chunk lies in. Chunk - address of memory chunk you want to free. Size - size of the chunk. SEE ALSO TrackPool, PoolAlloc ss.library/Printf ss.library/Printf NAME Printf -- Glue to dos/VPrintf. SYNOPSIS Printf(Text, Params); A0 A1 FUNCTION The VPrintf service in the dos library has its parameters in data registers, which usually involves many instructions for reordering of the arguments. This service does this required shuffling and calls VPrintf. INPUTS Text - pointer to format string Params - pointer to parameter array SEE ALSO Puts, PutsNL, FormatString, dos/VPrintf ss.library/Puts ss.library/Puts NAME Puts -- Glue to dos/FPuts. SYNOPSIS Puts(Text); A0 FUNCTION There exists no puts() in the dos library and FPuts() has its parameters in data registers, which usually involves many instructions for reordering of the arguments. This service does this required shuffling and calls FPuts with a filehandle of your stdout. INPUTS Text - pointer to message to print out SEE ALSO PutsNL, Printf, dos/FPuts ss.library/PutsNL ss.library/PutsNL NAME PutsNL -- Glue to dos/FPuts. SYNOPSIS PutsNL(Text); A0 FUNCTION There exists no puts() in the dos library and FPuts() does not emit a newline character after the string. This function does the same action as Puts and puts an additional newline after the string. INPUTS Text - pointer to message to print out SEE ALSO Puts, Printf, dos/FPuts ss.library/QuickSort ss.library/QuickSort NAME QuickSort -- Quickly sort an array. SYNOPSIS QuickSort(Base, NumEl, ElSize, CompFunc); A0 D0 D1 A1 FUNCTION Sort array of records in ascending order. Uses a variant of the QuickSort algorithm with minimal stack requirements. Stack overflow handled and reported (err_stack). See qsort() in any C book. Uses various optimizations depending on record size. INPUTS Base - address of first element of the array NumEl - number of elements (max. 65535, may be zero) ElSize - size of one element (max. 65535) CompFunc - pointer to function used for comparison of two elements. Called with A0=&El1, A1=&El2. Returns -1 if El1 < El2, 1 if El1 > El2, 0 if El1 == El2. May modify D1, A0 and A1. A5 passed without changes. SEE ALSO SortLongs, SortStrings, SortList, SortListName ss.library/RelinkObject ss.library/RelinkObject NAME RelinkObject -- Relink object to main resource list. SYNOPSIS RelinkObject(Object); A0 FUNCTION Relink tracked object to the first resource list. You are not allowed to relink master/slave object. This will be fixed in some future version. INPUTS Object - object to be relinked SEE ALSO TrackObject, CreateResList, FreeResList, FreeObject ss.library/RemExtension ss.library/RemExtension NAME RemExtension -- Remove last extension from file name. SYNOPSIS RemExtension(Name); A0 FUNCTION Remove filename extension if there's any. INPUTS Name - pointer to file name to remove extension of SEE ALSO AddExtension, SetExtension, GetExtension ss.library/ReportError ss.library/ReportError NAME ReportError -- Handle an error condition. SYNOPSIS ReportError(ErrorCode, Arg1, Arg2, Arg3); D0 A1 D2 D3 FUNCTION If the error bit corresponding to given error code is clear, error message is displayed and the program is stopped via ExitError(). If the error bit is set, nothing happens and ReportError() returns with zero in both D0 and D1. INPUTS ErrorCode - code of error which has happened (see ss.i) Arg1 - first argument to be substituted to error message Arg2 - second argument Arg3 - third argument SEE ALSO ExitError, DisplayError, DosError ss.library/SetExtension ss.library/SetExtension NAME SetExtension -- Set last extension in file name. SYNOPSIS Success = SetExtension(Name, Buffer, Extension, BufSize); D0 A0 A1 A2 D0 FUNCTION Set last extension of given file name or add it if there's no extension yet. INPUTS Name - name to set extension in Buffer - buffer to store the result to Extension - extension to be used BufSize - size of the buffer RESULT Success - TRUE if successful, FALSE if buffer overflow. SEE ALSO AddExtension, GetExtension, RemExtension ss.library/SimpleRequest ss.library/SimpleRequest NAME SimpleRequest -- Simple stub for EasyRequest. SYNOPSIS SimpleRequest(Text, Params, Gadgets); A0 A1 A2 FUNCTION Display a message using intuition/EasyRequest, but with significantly simpler arguments. For additional information see EasyRequest. INPUTS Text - pointer to message you want to display Params - pointer to optional parameters for printf-style formatting Gadgets - pointer to string containing texts for requester gadgets separated by '|' RESULT See EasyRequest SEE ALSO DisplayError, intuition/EasyRequest ss.library/SortList ss.library/SortList NAME SortList -- Sort linked list. SYNOPSIS SortList(List, Func); A0 A1 FUNCTION Sort standard double-linked list using user-supplied node comparison function. INPUTS List - pointer to list header Func - pointer to function used for comparision of two list nodes. A0=&&Node1, A1=&&Node2. Returns -1 if Node1 < Node2, 1 if Node1 > Node2 and 0 if Node1 == Node2. A5 is passed without changes. WARNING This function allocates a block of memory and _requires_ the err_memory bit set. SEE ALSO QuickSort, SortListName ss.library/SortListName ss.library/SortListName NAME SortListName -- Sort linked list by node name. SYNOPSIS SortListName(List); A0 FUNCTION Sort standard double-linked list by LN_NAME. (uses utility/Stricmp for comparison of node names) INPUTS List - pointer to list header WARNING This function allocates a block of memory and _requires_ the err_memory bit set. ss.library/SortLongs ss.library/SortLongs NAME SortLongs -- Sort an array of unsigned longwords. SYNOPSIS SortLongs(Array, NumEl); A0 D0 FUNCTION Sort an array of unsigned longword integers in ascending order. INPUTS Array - pointer to array you want to sort NumEl - number of elements SEE ALSO QuickSort, SortStrings ss.library/SortStrings ss.library/SortStrings NAME SortStrings -- Sort an array of string pointers. SYNOPSIS SortStrings(Array, NumEl); A0 D0 FUNCTION Sort an array of string pointers in ascending order of strings. Uses utility/Stricmp to compare the strings. INPUTS Array - pointer to array you want to sort NumEl - number of elements SEE ALSO QuickSort, SortLongs ss.library/StartupInit ss.library/StartupInit NAME StartupInit -- Standard startup procedure of program. SYNOPSIS StartupInit(StartupStruct, WbMsg); A0 D7 FUNCTION Performs standard startup initialization which includes: - Checks ss.library version requested by your program. - Allocate space for system variables and your own variables. The A5 register points to this memory region (directly to the ssbase item) allowing simple determination of the library base using MOVE.L (A5),A6. The system variables are stored below A5 (as described in SS.i) and may grow in future releases. Your own variables are stored above A5. The amount of user's variables is stored in the StartupStruct (as described below). - All system variables are initialized to their proper values. - All of your own variables are initialized to zeroes. - Automatically opens some libraries (dos, intuition, gfx, gadtools, utility) - Program name is determined and stored to system variable. - Current task is added to the CallerList, which allows to recover from a soft crash (see ExitCleanup for further explaination). - All actions requested by the tags are done (see below). - The arguments are parsed in both CLI and WB modes. If the WB has called us, the tool types are parsed using supplied template and converted to CLI arguments. If there's a multi-selected icon, it will be used as the first argument (if the first argument is /M, all multiselected icons will be parsed). If the program has been called as a default tool of some project, the project's name is used as the 1st argument. If there is some icon used as the first argument, its tool types override the program's ones. - If the program is started from Workbench, its current directory is set to its home directory or to directory containing the first argument. - Task's exception handler is replaced by custom one. It shows all address and data registers, the program counter and the status register (SR). The user may suspend the program, try to abort it (in this case, all resources tracked by SS functions are freed) or reboot the machine. [The exception code is NOT replaced if there is already another exception handler stored in RAM -> you can use breakpoints in your favourite debugger etc.] [The algorithm used for detection of custom exception handler might have some problems with future kickstarts larger than 1/2 Meg.] - Address of the ExitCleanup function is pushed onto stack allowing simple exit by usual RTS instruction. The tags parsed by this function are stored in a special (read: non-standard) format. This format uses variable-length tagitems: a) Special SSLib trackers (codes 0000-3FFF). These trackers have absolutely non-systematic arguments, therefore if SSLib encounters any unknown tag of this type (e.g., generated by newer version of the macros), it can't be simply ignored => the "Unknown Tracker" alert is shown and the program is terminated. If you use these trackers, make sure that your "required version number" value matches all these tag types you're using. This is usually done automatically by ssmac.h. b) Longword trackers. These are utility.library compatible with one small exception: TAG_IGNORE, TAG_MORE and TAG_SKIP are not supported and they act as TAG_END. The implementation is very simple: TAG_END ($00000000) is understood as a special SSLib tracker $0000 with the same meaning. All other longword trackers start with $8000, which says that StartupInit has to fetch next word as tag ID and next longword as tag parameters (in case of string args, it's a pointer to the string). The tag ID must be in range 8000-FFFF. c) Optional trackers (C000-FFFF). These trackers have variable size of argument, but there's a simple mechanism to determine this size: it's encoded in bits #12 and #13 of tag ID: 00 means no parameters, 01=one word, 10=one longword, 11=string (null-terminated and padded by zeroes to even length). If one of these optional trackers is encountered and cannot be interpreted, it's simply skipped. d) Extended trackers (4000-7FFF). Similar to Optional trackers, but can't be ignored. Many pointers in the tags are relative (marked as RelPtr). They can be simply generated by the following macro: RelPtr macro \@a dc.w \1-\@a endm INPUTS StartupStruct - pointer to startup structure (see StartupStruct in ss.i). It consists of two words followed by the tags. The first word contains requested size of user's variables and must be at least 4 (the first variable is always a pointer to base of ss.library). The second one specifies which version of ss.library does the program require. WbMsg - pointer to WorkBench startup message (you must get it manually). Can be any value when started from CLI. Must be 0 when started from process created by CreateProc, which is NOT started by the WorkBench. This sounds very complicated - see the start macro in ssmac.h if you are confused. RESULT A5 points to the variable zone. This value is required by all services of this library excluding where this doc says something other. If you call SSLib with different value in A5, weird things can occur (and really occur). TAGS sst_finish - End of TagList. sst_wbconsole - Create console window if started from WB. This window is used as standard input and output. sst_template (string,word) - Specifies argument template and offset from A5 to store the arguments on (see ParseArgs). sst_usertrk (RelPtr) - Defines user tracker types. You pass a relative tointer to UserTrkTypes structure: DC.B NumberOfTrackers,0 followed by RelPtrs to freeing routines (see FreeObject). sst_extrahelp (string) - Defines extra help string for argument parsing. sst_exitrout (RelPtr) - Define exit routine, which will be called by ExitCleanup (or any error exit routine) before any cleanup is done. This mechanism can be used for closing of windows and other similar actions. The exit routine may call ExitCleanup and the error exit routines, in which case it won't be called again. In case of fail during StartupInit, this routine is not called. sst_usererr (RelPtr) - Defines user's error routine. This routine will be called by DisplayError and all error routines which display errors. The routine will have the same parameters as DisplayError (A0=Message, A1=FormatData). If this routine calls any of the error functions, it will be called again. sst_nowbstart - Exit with error message when called from WB. sst_library (string,WV,W) - Open library of specified name and version (WV), store its base to variable specified by its offset from A5 (W). Exit with error message if can't be opened. sst_trylib (string,WV,W) - Try to open library (same function as previous tag, but if fails, the program will continue with base=0). sst_nowbargs - Don't parse WB arguments. sst_noprogname - Don't print program's name in error messages. sst_cputype (Min,Max) - Fail if CPU type isn't in specified range. 0=68000...4=68040, -1=no upper limit sst_fputype (Min,-1) - Fail if FPU type isn't in specified range. 0=none,1=68881,2=68882,3=68040 sst_sysver (Min,Max) - Fail if kickstart version isn't in specified range. sst_errorreq - Forces using of requesters for error messages. sst_errors (BitMap.L) - Disable automatic processing of specified errors (see SS.i for constants (err_xxx)). sst_wbconname (string) - Use WB Console specified by name sst_envvar (string) - Try to fetch default values of parameters from given environment variable. These parameters are overriden by values entered by the user. sst_poolsize (PoolSize.L) - Specify size of task's private memory pool. This pool is used for allocation of all trackers. Default size = 512 bytes. Specify higher values when using tracking very frequently. This tag MUST be specified before all other tags. The value must be an integer multiple of 8. sst_poolthresh (PoolThr.L) - Specify threshold of task's private memory pool (see TrackPool, PoolAlloc). Default threshold=373. Usage: rare. This tag MUST be specified directly after sst_poolsize or at the start if there is no poolsize tag. sst_nostderr - Force stderr=stdout. Don't open "*" for stderr. sst_noiconarg - don't pass names of multiselected icons as the first argument. They will be simply ignored. WARNING All registers excluding A4 and A6 are modified by this call. BUGS Argument parsing could be problematic when running from several debuggers (for example MonAm older than 3.04), because SSLib uses standard V37 way to pass them using buffered standard input. See also ssmac.h for some workaround. Also stderr may be incorrect in this case. But this is NOT a bug in ss.library, it is a result of bugs in the debuggers. SEE ALSO ExitCleanup, ExitError ss.library/StrCat ss.library/StrCat NAME StrCat -- Concatenate two strings. SYNOPSIS StrCat(Destination, Source); A0 A1 FUNCTION This function performs usual string concatenation. INPUTS Destination - destination string Source - source string RESULT A0 contains address of the null character at the end of the destination string. It allows to concatenate multiple strings without reloading of the destination pointer. ss.library/StrToL ss.library/StrToL NAME StrToL -- Convert string to long integer number. SYNOPSIS Value, Position = StrToL(String); D0 D1 A0 FUNCTION Convert string containing a number in ASCII form to binary form. It supports decimal, octal (prefixed by 0) and hexadecimal (prefixed by 0x or $) numbers. All spaces before the number are skipped. If there're any invalid characters, the standard error mechanism is used. If the user hadn't disabled it, the error message err_number is displayed and the program is terminated. INPUTS String - string to be converted RESULT Value - Value of number or 0 if invalid. Position (D1) - address of first invalid character if failed or zero if the input string contains valid number. ss.library/TestBreak ss.library/TestBreak NAME TestBreak -- Test if the user has pressed break. SYNOPSIS TestBreak(); FUNCTION Tests the CTRL-C signal and aborts the program if detected. NOTE Doesn't modify contents of D0,D1,A0,A1. Library base not needed in A6. SEE ALSO exec/SetSignal, arp/CheckAbort, arp/CheckBreak, dos.i ss.library/TestStack ss.library/TestStack NAME TestStack -- Check stack overflow. SYNOPSIS TestStack(); FUNCTION Test stack overflow and abort the program if it occured. The lowest possible value of SP is taken from sv_stklimit, which is initially set (by StartupInit) to TC_SPLOWER+128. NOTE Doesn't modify contents of D0,D1,A0,A1. Library base not needed in A6. The stack overflow error cannot be disabled. SEE ALSO TestBreak, StartupInit, ReportError ss.library/TrackAlloc ss.library/TrackAlloc NAME TrackAlloc -- Allocate memory and track it. SYNOPSIS MemBlock, Tracker = TrackAlloc(Size, Requirements); D0 D1 D0 D1 FUNCTION Allocate and track memory of specified size with specified attributes. If the memory is not available, exit with error message if its's enabled by the corresponding error bit. INPUTS Size - how large (in bytes) chunk of memory you want to allocate. Requirements - memory requirements (as for AllocMem) RESULT MemBlock - pointer to allocated memory block 0 if not enough memory of required type and error processing is disabled. Tracker (D1) - object tracker - trk_data contains base address of the block (as returned in D0), trk_ext is set to block size. SEE ALSO TrackAlloc, TrackAllocPub, FreeObject, exec/AllocMem ss.library/TrackAlloc ss.library/TrackAlloc NAME TrackAlloc -- Allocate cleared memory and track it. SYNOPSIS MemBlock, Tracker = TrackAlloc(Size); D0 D1 D0 FUNCTION Allocate, clear and track public memory of specified size. If the memory is not available, exit with error message if its's enabled by the corresponding error bit. If you want to allocate large block of memory and you don't need it to be cleared, use TrackAllocPub(Size) instead. INPUTS Size - how large (in bytes) chunk of memory you want to allocate. RESULT MemBlock - pointer to allocated and cleared memory block or 0 if not enough memory and error processing is disabled. Tracker (D1) - object tracker - trk_data contains base address of the block (as returned in D0), trk_ext is set to block size. SEE ALSO TrackAllocMem, TrackAllocPub, FreeObject, exec/AllocMem ss.library/TrackAllocPub ss.library/TrackAllocPub NAME TrackAllocPub -- Allocate public memory and track it. SYNOPSIS MemBlock, Tracker = TrackAllocPub(Size); D0 D1 D0 FUNCTION { no, this doesn't allocate a free place in a pub } Allocate region of public memory. Doesn't perform any clearing! Equivalent to TrackAllocMem(Size,MEMF_PUBLIC). INPUTS Size - how large (in bytes) chunk of memory you want to allocate. RESULT MemBlock - pointer to allocated memory block or 0 if not enough memory and error processing is disabled. Tracker (D1) - object tracker - trk_data contains base address of the block (as returned in D0), trk_ext is set to block size. SEE ALSO TrackAllocMem ss.library/TrackDevice ss.library/TrackDevice NAME TrackDevice -- Open device and track it. SYNOPSIS Error, Tracker, IORQ = TrackDevice(DevName, IORQ, Unit, Flags, D0 D1 A1 A0 A1 D0 D1 ErrTable); A2 FUNCTION Open device and track it. In case of difficulty, write an error message and abort the program if requested by corresponding error bit. INPUTS DevName - device name, case-sensitive IORQ - IORequest to use with this device (if IORQ<256, TrackIoRq(0,IORQ) will be called to create new IORequest, which will be linked by TrackSlave to device's tracker). Unit - device unit number Flags - OpenDevice flags ErrTable - optional pointer to error message table (this pointer MUST be specified if you want to use ChkDoIO, but it may be NULL). The table is a sequence of error definition blocks terminated by a block of 0 errors (both Min and NumErr fields are zero). Each block starts with two words of data: the first one contains number of first error message in the block, the second one contains number error messages. The header is followed by an array of longwords pointing to names of errors. RESULT Error - Error code or 0 if successful. Tracker (D1) - object tracker. trk_data contains pointer to associated IoRequest structure, trk_sizeof[0] points to the error table (as given in A2). IORQ (A1) - copy of trk_data (pointer to associated IORequest) SEE ALSO ChkDoIO, TrackIORQ, TrackPort, FreeObject, exec/OpenDevice ss.library/TrackDosObject ss.library/TrackDosObject NAME TrackDosObject -- Allocate a dos object and track it. SYNOPSIS DosObject, Tracker = TrackDosObject(Type, TagList); D0 D1 D0 A0 FUNCTION Allocate dos object and track it. Does usual error handling and reporting (err_memory). INPUTS Type - dos object type TagList - dos object tag list RESULT DosObject - pointer to allocated dos object or 0 if not successful. Tracker (D1) - object tracker. trk_data points to the object, trk_ext contains object type. SEE ALSO dos/AllocDosObject, FreeObject ss.library/TrackExtd ss.library/TrackExtd NAME TrackExtd -- Create an extended tracker. SYNOPSIS Tracker, Tracker, TrkExt = TrackExtd(Type, ExtSize); D0 A0 A1 D0:8 D1 FUNCTION Create an extended tracker structure and connect it to active resource list (if there's no resource list, one will be created). The extended tracker is a standard resource tracker, which has some additional data behind trk_sizeof. These bytes are for your own use. INPUTS Type - tracker type (see ss.i) ExtSize - size of tracker extension block RESULT Tracker - pointer to newly created object tracker Tracker (A0) - pointer to the tracker TrkExt (A1) - pointer to trk_ext field of the tracker SEE ALSO TrackObject, FreeObject ss.library/TrackIoRq ss.library/TrackIoRq NAME TrackIoRq -- Create an IoRequest and track it. SYNOPSIS IORQ, Tracker = TrackIoRq(OptionalPort, Size); D0 D1 A0 D0 FUNCTION Create an IO Request and track it. This function can use user-supplied message port or create special message port for this IORQ. In case of difficulty, writes error message and aborts the program if requested by corresponding error bit. INPUTS OptionalPort - pointer to message port to be used as a reply port for the IoRequest. If NULL, new port will be created including new signal. Size - size of the IoRequest or 0 for size of the IoExtStd structure. RESULT IORQ - pointer to newly created IoRequest structure. Tracker (D1) - obejct tracker. trk_data points to the IoRequest SEE ALSO TrackPort, TrackDevice, FreeObject ss.library/TrackLibrary ss.library/TrackLibrary NAME TrackLibrary -- Open a library and track it. SYNOPSIS Library, Tracker = TrackLibrary(LibName, Version); D0 D1 A0 D0 FUNCTION Open library and track it. If the library isn't available and you hadn't disabled it by the error bits, an error message will be displayed and the program will be aborted. INPUTS LibName - name of library, case is significant. Version - required minimal version (0=any). RESULT Library - pointer to library node or 0 if unsuccessful. Tracker (D1) - object tracker. trk_data contains pointer to base of the library (as returned in D0). SEE ALSO FreeObject, StartupInit, exec/OpenLibrary ss.library/TrackLinPool ss.library/TrackLinPool NAME TrackLinPool -- Create a linear memory pool and track it. SYNOPSIS LinPool = TrackLinPool(Quantum, Attributes); D0 D0 D1 FUNCTION Create a linear memory pool and track it. Linear pooled allocation is an extremely fast memory allocation strategy designed for allocating of small blocks of memory, which are freed together. The pool manager allocates memory in large blocks of given size (Quantum). It tries to use currently active block for each allocation request. If it fails, new block is created. INPUTS Quantum - allocation quantum Attributes - requested memory attributes (see AllocMem) RESULT LinPool - Pointer to linear memory pool tracker. SEE ALSO FreeObject, LinearAlloc, LinearAllocN ss.library/TrackLock ss.library/TrackLock NAME TrackLock -- Lock dos object and track it. SYNOPSIS Lock, Tracker = TrackLock(Name, LockMode); D0 D1 A0 D0 FUNCTION Lock dos object and track it. Error handling as usually. INPUTS Name - name of the object you want to lock. This pointer is stored in the tracker to be used later for reporting of errors, therefore you are not allowed to modify the name before freeing of the tracker. LockMode - lock mode (see dos.i) RESULT Lock - Dos lock or 0 if failed. Tracker (D1) - object tracker. trk_data contains the lock, trk_ext points to the name. SEE ALSO dos/Lock, FreeObject ss.library/TrackObject ss.library/TrackObject NAME TrackObject -- Create a standard tracker. SYNOPSIS Tracker, Tracker, TrkExt = TrackObject(Type); D0 A0 A1 D0:8 FUNCTION Create a standard tracker and connect it to active resource list (if there's no resource list, new one will be created). This function is used to track objects of your own types defined using the UserTrkTypes structure (tracker types in range $80 to $FF) or to track objects defined by ss.library extensions (not implemented yet). Your object freeing function will be called ONLY if the trk_data field contains non-null value. This suspiciously-looking rule allows you to track your objects simply with respect to all possible failures: - call TrackObject (if there isn't enough memory to do it -> aborted) - store A1 - allocate your object - restore A1 - store optional data at A1 if you need - store pointer to your object to -(A1) If allocation of your object fails and you abort the program, you don't have to free the tracker, because it will be done automatically by ExitCleanup (or other exit routine, which calls ExitCleanup) and your object-freeing routine won't be called. If you don't abort the program, you have simply to free the tracker using FreeObject and your object-freeing routine won't be called, too. INPUTS Type - tracker type (as described in ss.i) RESULT Tracker - pointer to newly created object tracker Tracker (A0) - pointer to the tracker TrkExt (A1) - pointer to trk_ext field of the tracker NOTE There are some cases in which you want to suppress freeing of already tracked object (for example if you write some patch utility leaving patch code in memory after successful exit, but freeing it in case of failure). It can be solved very simply by calling Remove(Tracker) - the tracker will be removed cleanly. If you use this method, ExitCleanup will destroy the trackers themself (they are stored in a memory pool which is private to each task and is freed during the cleanup), but the tracked objects are not affected. Do not call FreeObject on disconnected objects. Another way to do such a thing is to set Tracker.trk_type to trt_null, but it makes using of additional FreeObject() impossible, because it will free only the tracker, not the tracked object. You are not allowed to manipulate the positions of objects in the lists. If you really need to do such a thing, use RelinkObject(). SEE ALSO CreateResList, FreeObject, FreeResList, GetResList, TrackRoutine, TrackExtd, RelinkObject ss.library/TrackOpen ss.library/TrackOpen NAME TrackOpen -- Open a file and track it SYNOPSIS FH, Tracker = TrackOpen(Name, OpenMode); D0 D1 A0 D0 FUNCTION Open a file and track it. Does usual error checking and handling (see some other tracking function). INPUTS Name - name of the file you want to open. This pointer is stored in the tracker to be used later in error reports, therefore you are not allowed to modify the name until you free the tracker. OpenMode - Open() mode - see dos/dos.i - MODE_*. You can also use one of SS open modes: OPEN_OLD (a synonym to MODE_OLDFILE, but slightly shorter value movable by MOVEQ), OPEN_NEW (identical to MODE_NEWFILE) or OPEN_APPEND (uses MODE_READWRITE and Seek() to EOF). RESULT FH - File handle or 0 if failed. Tracker (D1) - object tracker. trk_data contains file handle, trk_ext points to file name. SEE ALSO dos/Open, dos.i, FreeObject ss.library/TrackPool ss.library/TrackPool NAME TrackPool -- Create private memory pool and track it. SYNOPSIS MemPool = TrackPool(Quantum, Threshold, Attributes); D0 D0 D1 D2 FUNCTION Create a memory pool and track it. Error checking is performed according to common rules (see elsewhere what does it mean). Pooled allocation is a relatively fast memory allocation strategy designed for manipulating small blocks of memory. It's based on memory chunks, each of them has given size (Quantum). Any memory block requested by PoolAlloc, which size is less or equal to Threshold, is allocated inside one of memory chunks. Blocks greater than Threshold are allocated using standard AllocMem and linked to the pool. All memory blocks in the pool can be freed separately or simultaneously by FreeObject. INPUTS Quantum - allocation quantum Threshold - size of largest block allocated inside chunks Attributes - requested memory attributes (MEMF_#? - see AllocMem) RESULT MemPool - pointer to memory pool tracker SEE ALSO FreeObject, PoolAlloc, PoolFree, exec/AllocMem ss.library/TrackPort ss.library/TrackPort NAME TrackPort -- Create a message port and track it. SYNOPSIS Port, Tracker = TrackPort(); D0 D1 FUNCTION Create a message port and track it. Does usual error checking and handling. RESULT Port - pointer to newly created MsgPort structure. Tracker (D1) - object tracker. trk_data points to the port. SEE ALSO exec/CreateMsgPort, FreeObject, TrackIORQ ss.library/TrackRoutine ss.library/TrackRoutine NAME TrackRoutine -- Create tracker with custom freeing routine. SYNOPSIS Tracker = TrackRoutine(Routine, Args); D0 A0 A1 FUNCTION Define a tracker, which will call your routine in time of freeing. The Args you supply will be passed in A0 to your routine. If args=0, no routine will be called. For the reason of this suspicious action, see TrackObject (there are applied the same rules). INPUTS Routine - pointer to routine You wish to call. The routine should leave intact all registers except D0-D1/A0-A1/A6. Args - user data passed to the routine in time of resource freeing. RESULT Tracker - tracker of expected type. A1 points to Args and can be used in similar way as in TrackObject, but you should use (A1) instead of -(A1). SEE ALSO TrackObject, FreeObject ss.library/TrackSignal ss.library/TrackSignal NAME TrackSignal -- Allocate signal and track it. SYNOPSIS Signal, Tracker = TrackSignal(); D0 D1 FUNCTION Allocate a signal and track it. Does usual error checking and handling. RESULT Signal - Number of signal or -1 if there are no free signals. Tracker (D1) - object tracker. trk_data contains number of signal. SEE ALSO exec/AllocSignal, FreeObject ss.library/TrackSlave ss.library/TrackSlave NAME TrackSlave -- Join two trackers. SYNOPSIS TrackSlave(Master, Slave); A0 A1 FUNCTION Connect Slave to a list of Master's slaves and re-connect the Master to the front of current resource list, therefore it will be freed before the slaves. The linkage mechanism uses the Tracker.trk_ext field as pointer to the first slave. It causes that standard trackers (excluding trt_null) cannot be used as masters. The routine tracker (obtained via TrackRoutine) can be used, but its entry data (passed in A0 to user's resource freeing routine) will be overwritten (but it won't be 0 in any case -> the routine is called everytime). The slaves are freed in LIFO order (the last slave will be freed as the first one). INPUTS Master - tracker to be used as the master Slave - tracker to be used as the slave SEE ALSO TrackObject, FreeObject